<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>

<!--
========================================================================
 *  Copyright by KNIME AG, Zurich, Switzerland
 *  Website: http://www.knime.com; Email: contact@knime.com
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License, Version 3, as
 *  published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, see <http://www.gnu.org/licenses>.
 *
 *  Additional permission under GNU GPL version 3 section 7:
 *
 *  KNIME interoperates with ECLIPSE solely via ECLIPSE's plug-in APIs.
 *  Hence, KNIME and ECLIPSE are both independent programs and are not
 *  derived from each other. Should, however, the interpretation of the
 *  GNU GPL Version 3 ("License") under any applicable laws result in
 *  KNIME and ECLIPSE being a combined program, KNIME AG herewith grants
 *  you the additional permission to use and propagate KNIME together with
 *  ECLIPSE with only the license terms in place for ECLIPSE applying to
 *  ECLIPSE and the GNU GPL Version 3 applying for KNIME, provided the
 *  license terms of ECLIPSE themselves allow for the respective use and
 *  propagation of ECLIPSE together with KNIME.
 *
 *  Additional permission relating to nodes for KNIME that extend the Node
 *  Extension (and in particular that are based on subclasses of NodeModel,
 *  NodeDialog, and NodeView) and that only interoperate with KNIME through
 *  standard APIs ("Nodes"):
 *  Nodes are deemed to be separate and independent programs and to not be
 *  covered works.  Notwithstanding anything to the contrary in the
 *  License, the License does not apply to Nodes, you are not required to
 *  license Nodes under the License, and you are granted a license to
 *  prepare and propagate Nodes, in each case even if such Nodes are
 *  propagated with or for interoperation with KNIME.  The owner of a Node
 *  may freely choose the license terms applicable to such Node, including
 *  when such Node is propagated with or for interoperation with KNIME.
====================================================================
-->
</head>


<body>

Contains all classes needed to implement a new node in the workflow.
<br>

<br>

It contains all classes that will be instantiated when a new node is plugged
into the workflow. And it
provides abstract classes {@link org.knime.core.node.NodeModel}, {@link
org.knime.core.node.NodeView} and {@link org.knime.core.node.NodeDialogPane}
that must be extended when a new type of node is implemented.
<br>

<br>

Nodes are connected to each other through their ports. Data or models are
exchanged over these connections. Nodes implement a certain task, like reading
in data, analyzing, displaying, writing out data, etc. The final class {@link
org.knime.core.node.Node}, together with the abstract {@link
org.knime.core.node.NodeModel}, {@link org.knime.core.node.NodeDialog}, and
{@link org.knime.core.node.NodeView} do most of the infrastructural work that is
needed to connect a new node in the workflow.
<br>

<br>

Nodes have different states:
<em>not executable</em>
,
<em>executable</em>
, or
<em>executed</em>
. A node is not executable until all ports are connected to predecessor nodes
and all required parameters are set (which depends on the task of the specific
node model). If a node is executable the execution can be invoked, causing the
node to read in the {@link org.knime.core.data.DataTable}s (see the {@link
org.knime.core.data data} package) and models from its inputs, to do what ever
it is supposed to do with the data and/or models (again depending on the
specific incarnation of the node model), and to provide new {@link
org.knime.core.data.DataTable}s at its output ports. If execution finishes
successfully the node is in the state
<em>executed</em>
.
<br>

<br>

Nodes should implement the following Model-View-Controller concept. The model
computes and stores the content of the node. A view provides a view to the
actual state of the model; it doesn't change the model. There could be more than
one view, providing different kinds of views onto the model. The controller is
the part that modifies the model. In our case there is more than one controller.
The {@link org.knime.core.node.NodeDialogPane} implements a controller that sets
the parameters in the {@link org.knime.core.node.NodeModel} before it can be
executed.
<br>

<br>

<img alt="the intestines of a node" src="doc-files/Node.png"
  style="height: 810px; width: 842px;">
<br>

<br>

The communication between the dialog and the model is happening through {@link
org.knime.core.node.NodeSettings NodeSettings} objects. The dialog will read the
current settings of the model before opening, and all user settings will be
transfered back into the model (as a side effect, you may not store settings for
a node model that are not handled by the dialog, because the). For this, the
derived dialog and model must implement load and save settings methods, the
model will have in addition a validate settings method. The transfer of these
objects is implemented in the abstract classes.
<br>

<br>

Things a new Node implementation (here called
<em>MyNode</em>
...) must&nbsp; provide:
<br>

<ul>

  <li>a new class <code style="text-decoration: underline;">MyNodeModel</code>
  derived from {@link org.knime.core.node.NodeModel NodeModel} representing the
  model of a node. The <code>MyNodeModel</code> must implement at least:</li>

  <li>a method <code style="text-decoration: underline;">execute(...)</code>,
  which performs the actual task of the node, invoked during <code>executeNode()</code>.
  It gets the {@link org.knime.core.data.DataTable}s from the inputs of the node
  as parameters and must provide {@link org.knime.core.data.DataTable}s for the
  outputs of the node as result. <br>

  </li>

  <li>a method <code style="text-decoration: underline;">configure(...)</code>,
  which provides meta information about the {@link
  org.knime.core.data.DataTable}s that will be generated during execution - at a
  time before execution. Some nodes can provide information upfront about the
  structure of the {@link org.knime.core.data.DataTable}s they will create,
  either after parameters are set or after they've received information about
  the incoming {@link org.knime.core.data.DataTable}s. They should return this
  meta information in {@link org.knime.core.data.DataTableSpec}s as a result of
  this method. The others just return <code>null</code>. In addition, this
  method must indicate whether the model received all settings and is ready to
  be executed.<br>

  </li>

  <li>a method <code style="text-decoration: underline;">saveSettingsTo(...)</code>
  that will write out the current user settings of the model into a {@link
  org.knime.core.node.NodeSettings} object.</li>

  <li>a method <code style="text-decoration: underline;">validateSettings(...)</code>
  which checks a settings object telling if the settings in there are complete
  and consistent.</li>

  <li>a method <code style="text-decoration: underline;">loadValidatedSettings(...)</code>
  which sets new values in the internal settings of the model from a valid
  settings object.</li>

  <li>a method <code style="text-decoration: underline;">reset()</code>
  that clears out all internal data depending on or derived from any incoming
  data from predecessors.</li>

  <li>a method <code style="text-decoration: underline;">saveInternalSettings(...)</code>
  which must save all internal data derived from the input data (that is
  basically the data cleared during <code>reset()</code>) onto disk.</li>

  <li>a method <code style="text-decoration: underline;">loadInternalSettings(...)</code>
  that must be able to read back the data written during <code>saveInternalSettings(...)</code>.
  After <code>loadInternalSettings(...)</code> the model must be in the same
  state as after execute. <code>loadInternalSettings(...)</code> is called when
  loading a workflow to re-establish the state of all nodes before closing the
  flow.</li>

  <li>a new class <code style="text-decoration: underline;">MyNodeFactory</code>
  derived from {@link org.knime.core.node.NodeFactory NodeFactory}, that returns
  new instances of <code>MyNodeModel</code>, <code>MyNodeView</code>, and <code>MyNodeDialog</code>,
  if implemented. The instances created by one factory must work together and
  form the Model-View-Controller concept for that particular incarnation of a
  node. <code>NodeView</code> and <code>NodeDialog</code> are optional (the
  factory can return <code>null</code>), a NodeModel must always be provided.</li>

  <li>in addition a file <code style="text-decoration: underline;">MyNodeFactory.xml</code>
  must be created, which contains the description of the node, its
  functionality, its ports, views, and dialog options. The information will be
  read from the factory and can be retrieved from there. Please read <a
    href="doc-files/NodeFactory_xml.html">here</a> for the content and structure
  of the <a href="doc-files/NodeFactory_xml.html">NodeFactory.xml</a> file.</li>

</ul>

In addition, a node should think about providing a {@link
org.knime.core.node.property.hilite.HiLiteHandler HiLiteHandler}. These are
independent and separate instances storing the hilite status for each data point
in a {@link org.knime.core.data.DataTable}. Any (part of a) node can ask a
hilite handler for this property of a given row, and it can also register as
listener to be notified of any change in the properties of any row. On the other
hand each node can set new properties in a handler and can expect these
properties to show in all nodes listening.
<br>

New hilite handler instances must be created by nodes that create {@link
org.knime.core.data.DataTable}s with new {@link org.knime.core.data.RowKey}s at
their outputs. In the method {@link
org.knime.core.node.NodeModel#getOutHiLiteHandler(int)} the model decides for
each output port which {@link org.knime.core.node.property.hilite.HiLiteHandler
HiLiteHandler} goes along with the {@link org.knime.core.data.DataTable}
provided at this output port. The default implementation in the abstract {@link
org.knime.core.node.NodeModel} just passes along the {@link
org.knime.core.node.property.hilite.HiLiteHandler HiLiteHandler} it receives at
input port "0". If it has no input port, it will instantiate a new {@link
org.knime.core.node.property.hilite.HiLiteHandler HiLiteHandler}, as it must be
the beginning of a data flow then. There are default hilite handler
implementations (see package {@link org.knime.core.data.property property}) that
can be used when a new handler instance is needed.
<br>

</body>
</html>
